TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
-tmpl_sources = foo
+tmpl_sources = \
+ tmpl/creating.sgml \
+ tmpl/file-loading.sgml \
+ tmpl/gdk-pixbuf-io.sgml \
+ tmpl/gdk-pixbuf-loader.sgml \
+ tmpl/gdk-pixbuf-unused.sgml \
+ tmpl/gdk-pixbuf.sgml \
+ tmpl/gnome-canvas-pixbuf.sgml \
+ tmpl/refcounting.sgml \
+ tmpl/rendering.sgml
gdk_pixbuf_docdir = $(HTML_DIR)
-gdk_pixbuf_doc_DATA = \
- gdk-pixbuf.html \
- gdk-pixbuf.hierarchy \
- gdk-pixbuf.types \
- gdk-pixbuf-scan.c \
- gdk-pixbuf-decl.txt \
+gdk_pixbuf_doc_DATA = \
+ gdk-pixbuf.html \
+ gdk-pixbuf.hierarchy \
+ gdk-pixbuf.types \
+ gdk-pixbuf-decl.txt \
gdk-pixbuf-sections.txt
EXTRA_DIST = $(gdk_pixbuf_doc_DATA)
<RETURNS>void </RETURNS>
GdkPixbuf *pixbuf, gpointer user_data
</USER_FUNCTION>
+<USER_FUNCTION>
+<NAME>ModuleUpdatedNotifyFunc</NAME>
+<RETURNS>void </RETURNS>
+GdkPixbuf *pixbuf, gpointer user_data, guint x, guint y, guint width, guint height
+</USER_FUNCTION>
<STRUCT>
<NAME>GdkPixbufModule</NAME>
</STRUCT>
GdkPixbuf *(* load_xpm_data) (const gchar **data);
/* Incremental loading */
- gpointer (* begin_load) (ModulePreparedNotifyFunc func, gpointer user_data);
+ gpointer (* begin_load) (ModulePreparedNotifyFunc prepare_func, ModuleUpdatedNotifyFunc update_func, gpointer user_data);
void (* stop_load) (gpointer context);
gboolean (* load_increment)(gpointer context, const gchar *buf, guint size);
};
<SECTION>
<FILE>gdk-pixbuf-io</FILE>
ModulePreparedNotifyFunc
+ModuleUpdatedNotifyFunc
GdkPixbufModule
gdk_pixbuf_get_module
gdk_pixbuf_load_module
<!-- ##### SECTION Title ##### -->
-Creating a Pixbuf from Data in Memory
+Image Data in Memory
<!-- ##### SECTION Short_Description ##### -->
Creating a pixbuf from image data that is already in memory.
<!-- ##### SECTION Long_Description ##### -->
<para>
+ The most basic way to create a pixbuf is to wrap an existing
+ #ArtPixBuf structure with a #GdkPixbuf to add reference counting
+ capabilities to it. The gdk_pixbuf_new_from_art_pixbuf() performs
+ this operation.
+ </para>
+ <para>
+ As a convenience, you can use the gdk_pixbuf_new_from_data()
+ function to wrap an existing data buffer with a #GdkPixbuf. You
+ need to specify the destroy notification function that will be
+ called when the data buffer needs to be freed; this will happen
+ when the pixbuf's reference count drops to zero and thus the
+ #ArtPixBuf needs to be destroyed. If you have a chunk of static
+ data compiled into your application, you can pass in #NULL as the
+ destroy notification function so that the data will not be freed.
</para>
-<!-- ##### SECTION See_Also ##### -->
-<para>
+ <para>
+ The gdk_pixbuf_new() function can be used as a convenience to
+ create a pixbuf with an empty buffer. This is equivalent to
+ allocating a data buffer using malloc() and then wrapping it with
+ gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will
+ compute an optimal rowstride so that rendering can be performed
+ with an efficient algorithm.
+ </para>
-</para>
+ <para>
+ As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
+ function to create a pixbuf from inline XPM image data.
+ </para>
+
+<!-- ##### SECTION See_Also ##### -->
+ <para>
+ #ArtPixBuf
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
<para>
</para>
@data:
-@Returns:
+@Returns:
<!--
Local variables:
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
+
+
</para>
@filename:
-@Returns:
+@Returns:
<!--
Local variables:
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
+
+
@user_data:
+<!-- ##### USER_FUNCTION ModuleUpdatedNotifyFunc ##### -->
+<para>
+
+</para>
+
+@pixbuf:
+@user_data:
+@x:
+@y:
+@width:
+@height:
+
+
<!-- ##### STRUCT GdkPixbufModule ##### -->
<para>
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_n_channels ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_has_alpha ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_bits_per_sample ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_pixels ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_width ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_height ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_rowstride ##### -->
</para>
-@pixbuf:
+@pixbuf:
@Returns:
<!--
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
+
+
GnomeCanvasPixbuf
<!-- ##### SECTION Short_Description ##### -->
-
+Canvas item to display #GdkPixbuf images.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ This canvas item displays #GdkPixbuf images. It handles full
+ affine transformations in both GDK and antialiased modes, and also
+ supports <ulink
+ url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
+ translation semantics for absolute pixel values.
+ </para>
+
+ <para>
+ #GdkPixbuf structures may be shared among different pixbuf canvas
+ items; the pixbuf item uses #GdkPixbuf's reference counting
+ functions for this.
+ </para>
<!-- ##### SECTION See_Also ##### -->
+ <para>
+ #GnomeCanvas, #GdkPixbuf
+ </para>
+
+<!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
+ <para>
+ Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
+ </para>
+
+@obj: A GTK+ object.
+
+
+<!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
+ <para>
+ Contains a pointer to a #GdkPixbuf structure that will be used by
+ the pixbuf canvas item as an image source. When a pixbuf is set
+ its reference count is incremented; if the pixbuf item kept a
+ pointer to another #GdkPixbuf structure, the reference count of
+ this structure will be decremented. When a pixbuf is queried, a
+ reference count will not be added to the return value; you must do
+ this yourself if you intend to keep the pixbuf structure around.
+ </para>
+
+<!-- ##### ARG GnomeCanvasPixbuf:width_set ##### -->
+ <para>
+ Determines whether the
+ </para>
+
+<!-- ##### ARG GnomeCanvasPixbuf:width_pixels ##### -->
<para>
</para>
-<!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+ <para>
+ Contains the width of the image in the pixbuf canvas item.
+ </para>
+
+<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
<para>
</para>
-@obj:
+<!-- ##### ARG GnomeCanvasPixbuf:height_set ##### -->
+<para>
+</para>
-<!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:height_pixels ##### -->
<para>
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
<para>
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:width_set ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
<para>
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:width_pixels ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:x_pixels ##### -->
<para>
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
<para>
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:height_set ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
<para>
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:height_pixels ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:y_pixels ##### -->
<para>
</para>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
<!-- ##### SECTION See_Also ##### -->
<para>
- #GdkPixbuf
- #ArtPixBuf
+ #GdkPixbuf, #ArtPixBuf
</para>
<!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
@pixbuf:
-
<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
+
+
<!-- ##### SECTION Title ##### -->
-rendering
+Rendering
<!-- ##### SECTION Short_Description ##### -->
-
+Rendering a Pixbuf to a GDK Drawable.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ The GdkPixbuf library provides several convenience functions to
+ render pixbufs to GDK drawables. It uses the GdkRGB to render the
+ image data.
+ </para>
+
+ <para>
+ At this point there is not a standard alpha channel extension for
+ the X Window System, so it is not possible to use full opacity
+ information when painting images to arbitrary drawables. The
+ GdkPixbuf convenience functions will threshold the opacity
+ information to create a bi-level clipping mask (black and white),
+ and use that to draw the image onto a drawable.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ GdkRGB
+ </para>
<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
-<para>
-
-</para>
-
-@GDK_PIXBUF_ALPHA_BILEVEL:
-@GDK_PIXBUF_ALPHA_FULL:
+ <para>
+ These values can be passed to
+ gdk_pixbuf_render_to_drawable_alpha() to control how the alpha
+ chanel of an image should be handled. This function can create a
+ bilevel clipping mask (black and white) and use it while painting
+ the image. In the future, when the X Window System gets an alpha
+ channel extension, it will be possible to do full alpha
+ compositing onto arbitrary drawables. For now both cases fall
+ back to a bilevel clipping mask.
+ </para>
+
+@GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
+will be created and used to draw the image. Pixels below 0.5 opacity
+will be considered fully transparent, and all others will be
+considered fully opaque.
+@GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
+In the future it will do full alpha compositing.
<!-- ##### FUNCTION gdk_pixbuf_render_to_drawable_alpha ##### -->
<para>
@dest_y:
@width:
@height:
-@alpha_threshold:
+@alpha_threshold:
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
+1999-11-04 Federico Mena Quintero <federico@redhat.com>
+
+ * doc/tmpl/rendering.sgml: Populated.
+
+ * doc/Makefile.am: Added the template files.
+
1999-11-04 Havoc Pennington <hp@pobox.com>
* src/gdk-pixbuf-render.c (gdk_pixbuf_render_to_drawable): In
* drops to zero, or NULL if the data should not be freed.
* @dfunc_data: Closure data to pass to the destroy notification function.
*
- * Creates a new &GdkPixbuf out of in-memory RGB data.
+ * Creates a new #GdkPixbuf out of in-memory RGB data.
*
- * Return value: A newly-created &GdkPixbuf structure with a reference count of
+ * Return value: A newly-created #GdkPixbuf structure with a reference count of
* 1.
**/
GdkPixbuf *
* gdk_pixbuf_loader_get_type:
* @void:
*
- * Registers the &GdkPixubfLoader class if necessary, and returns the type ID
+ * Registers the #GdkPixubfLoader class if necessary, and returns the type ID
* associated to it.
*
- * Return value: The type ID of the &GdkPixbufLoader class.
+ * Return value: The type ID of the #GdkPixbufLoader class.
**/
GtkType
gdk_pixbuf_loader_get_type (void)
* gdk_pixbuf_new_from_art_pixbuf:
* @art_pixbuf: A libart pixbuf.
*
- * Creates a &GdkPixbuf by wrapping a libart pixbuf.
+ * Creates a #GdkPixbuf by wrapping a libart pixbuf.
*
- * Return value: A newly-created &GdkPixbuf structure with a reference count of
+ * Return value: A newly-created #GdkPixbuf structure with a reference count of
* 1.
**/
GdkPixbuf *
* @width: Width of image in pixels.
* @height: Height of image in pixels.
*
- * Creates a new &GdkPixbuf structure and allocates a buffer for it. The buffer
+ * Creates a new #GdkPixbuf structure and allocates a buffer for it. The buffer
* has an optimal rowstride. Note that the buffer is not cleared; you will have
* to fill it completely.
*
- * Return value: A newly-created &GdkPixbuf, or NULL if not enough memory
- * could be allocated for the image buffer.
+ * Return value: A newly-created #GdkPixbuf with a reference count of 1, or NULL
+ * if not enough memory could be allocated for the image buffer.
**/
GdkPixbuf *
gdk_pixbuf_new (ArtPixFormat format, gboolean has_alpha, int bits_per_sample,
* gnome_canvas_pixbuf_get_type:
* @void:
*
- * Registers the &GnomeCanvasPixbuf class if necessary, and returns the type ID
+ * Registers the #GnomeCanvasPixbuf class if necessary, and returns the type ID
* associated to it.
*
- * Return value: The type ID of the &GnomeCanvasPixbuf class.
+ * Return value: The type ID of the #GnomeCanvasPixbuf class.
**/
GtkType
gnome_canvas_pixbuf_get_type (void)
* opacity information for images with an alpha channel; the GC must already
* have the clipping mask set if you want transparent regions to show through.
*
- * For an explanation of dither offsets, see the GdkRGB documentation. In brief, the
- * dither offset is important when scrolling (so you can redraw half an image but keep the
- * dithering "lined up" between the part you drew first and the part you drew previously).
- * For unscrolled images, the offset can always be 0.
+ * For an explanation of dither offsets, see the GdkRGB documentation. In
+ * brief, the dither offset is important when re-rendering partial regions of an
+ * image to a rendered version of the full image, or for when the offsets to a
+ * base position change, as in scrolling. The dither matrix has to be shifted
+ * for consistent visual results. If you do not have any of these cases, the
+ * dither offsets can be both zero.
**/
void
gdk_pixbuf_render_to_drawable (GdkPixbuf *pixbuf,
* Renders a rectangular portion of a pixbuf to a drawable. This is done using
* GdkRGB, so the specified drawable must have the GdkRGB visual and colormap.
*
- * This function has a performance penalty; it makes two synchronous
- * round trips to the X server (creating a bitmask and a GC), and it
- * draws the contents of the bitmask. If performance is crucial,
- * consider handling alpha yourself and using
- * gdk_pixbuf_render_to_drawable(). On the other hand it's more convenient
- * than gdk_pixbuf_render_to_drawable() because it handles the alpha channel.
+ * When used with #GDK_PIXBUF_ALPHA_BILEVEL, this function has to create a bitmap
+ * out of the thresholded alpha channel of the image and, it has to set this
+ * bitmap as the clipping mask for the GC used for drawing. This can be a
+ * significant performance penalty depending on the size and the complexity of
+ * the alpha channel of the image. If performance is crucial, consider handling
+ * the alpha channel yourself (possibly by caching it in your application) and
+ * using gdk_pixbuf_render_to_drawable() or GdkRGB directly instead.
**/
void
gdk_pixbuf_render_to_drawable_alpha (GdkPixbuf *pixbuf, GdkDrawable *drawable,
* gdk_pixbuf_loader_get_type:
* @void:
*
- * Registers the &GdkPixubfLoader class if necessary, and returns the type ID
+ * Registers the #GdkPixubfLoader class if necessary, and returns the type ID
* associated to it.
*
- * Return value: The type ID of the &GdkPixbufLoader class.
+ * Return value: The type ID of the #GdkPixbufLoader class.
**/
GtkType
gdk_pixbuf_loader_get_type (void)
projects / gtk4.git / commitdiff